🧭 SCOUTS NEEDLE COMPASS – AUTO TRACKING
SOLAR COMPASS ("Sharky Shadows" Methodology)

1. DESCRIPTION

Scouts Needle Compass – Auto Tracking is a lightweight, fully offline-capable, browser-based solar compass application.

The application determines direction using:

• GPS location (latitude & longitude)
• Real-time solar position calculations
• Reverse-sun shadow alignment
• 16-point compass direction system

The compass needle is manually rotated to match a real-world shadow. The system then calculates the relative directional target.

This version (Vp1) is optimized for offline hosting and minimal file size.

2. FEATURES

• Real-time GPS tracking (high accuracy mode)
• Solar azimuth calculation using atan2() quadrant resolution
• Reverse sun (shadow direction) computation
• Interactive SVG needle (touch + mouse support)
• 16-direction compass output: N, NNE, NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW
• Internal degree precision (decimal accuracy)
• LocalStorage persistence (coordinates + azimuth)
• Fully self-contained single HTML file
• No external libraries
• No internet required after loading

3. SOLAR CALCULATION MODEL

This application uses a simplified astronomical solar position model derived from standard spherical trigonometry.

It is NOAA-style in structure but is NOT the full NOAA Solar Position Algorithm (SPA).

The model includes:

• Day-of-year calculation
• Solar declination (seasonal approximation)
• Equation of Time (simplified form)
• Solar noon adjustment
• Hour angle calculation
• Solar elevation computation
• Solar azimuth calculation using Math.atan2() for proper quadrant determination

Azimuth is resolved using:

azimuth = atan2(y, x)

This ensures correct 0–360° directional output across all quadrants.

The model does NOT include:

• Full fractional year series expansion
• High-order declination corrections
• Atmospheric refraction correction
• Sub-arcminute precision refinements

Accuracy range is typically ±0.5° to ±1.5° (depending on latitude and season).

For shadow-based field navigation, this accuracy is more than sufficient. In practical use, GPS precision usually introduces more positional error than the solar math itself.

4. HOW IT WORKS

Step 1 – GPS Acquisition
The browser retrieves latitude and longitude using the Geolocation API.

Step 2 – Solar Position Calculation
The app computes solar azimuth based on current UTC time and location.

Step 3 – Shadow Direction

shadowAzimuth = (sunAzimuth + 180) % 360

Step 4 – User Alignment
The user rotates the SVG needle to match the real-world shadow.

Step 5 – Target Calculation

target = (shadowAzimuth - currentNeedleAzimuth + 360) % 360

Step 6 – Display
The target is shown as one of the 16 compass directions. Internally, calculations remain degree-based for precision.

5. REQUIREMENTS

• Modern mobile browser
• GPS enabled
• HTTPS hosting (required for Geolocation API)
• Direct sunlight for proper shadow alignment

Recommended: Mobile device with touch screen.

6. PRIVACY

• No data is transmitted.
• No external APIs are used.
• All calculations occur locally.
• Coordinates are stored only in browser localStorage.
• No tracking or analytics.

7. FILE STRUCTURE

Single standalone file: scouts_needle_compass_offline_16_direction_Vp1.html

Contains:

• HTML structure
• CSS styling
• SVG compass graphics
• JavaScript solar math engine
• GPS tracking logic

8. LIMITATIONS

• Not usable at night.
• Requires visible sunlight.
• GPS accuracy affects precision.
• Not a certified navigation instrument.
• Solar calculations are simplified (navigation-grade, not observatory-grade).

9. VERSION

• Version: Vp1
• Direction System: 16-point compass
• Operation Mode: Manual shadow alignment
• Tracking Mode: Automatic GPS watchPosition

10. LICENSE

This project is licensed under the MIT License.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files, to deal in the Software without restriction, including without limitation the rights to:

• Use
• Copy
• Modify
• Merge
• Publish
• Distribute
• Sublicense
• Sell copies

Subject to inclusion of the copyright notice.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

11. DISCLAIMER

This application is intended for educational, experimental, scouting, and solar-navigation purposes only.

The author assumes no liability for misuse, navigation errors, or damages arising from use of this software.